; Improve documentation of 'modifier-bar-mode'

* doc/emacs/custom.texi (Modifier Keys):
* doc/emacs/frames.texi (Tool Bars):
* lisp/tool-bar.el (modifier-bar-mode): Improve documentation of
'modifier-bar-mode'.

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index f69187ff2397693645497ea11dc274ae73d0185b..6a3e9d899dc06802b608b41aa224ab7c717fc289 100644 (file)
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -2164,6 +2164,10 @@ You can similarly enter the Shift, Control, and Meta modifiers by
 using @kbd{C-x @@ S}, @kbd{C-x @@ c}, and @kbd{C-x @@ m}, respectively,
 although this is rarely needed.
 
+  On graphical terminals, you can enable the Modifier Bar mode, which
+allows simulating the missing modifier keys by clicking a tool-bar
+button.  @xref{Tool Bars}.
+
 @node Function Keys
 @subsection Rebinding Function Keys
 

diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index e0d8a60707208fba561d4278c69749c4fe8bf373..8225825e261a02ca0ed9685c3a2730c20b62c4b8 100644 (file)
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -1343,15 +1343,18 @@ displayed by moving the mouse pointer to the top of the screen.
 @cindex displaying modifier keys in the tool bar
 @cindex mode, Modifier Bar
 @cindex Modifier Bar
-  Keyboards often lack one or more of the modifier keys that Emacs
-might want to use, making it difficult or impossible to input key
-sequences that contain them.  Emacs can optionally display a list of
-buttons that act as substitutes for modifier keys within the tool bar;
-these buttons are also referred to as the ``modifier bar''.  Clicking
-an icon within the modifier bar will cause a modifier key to be
-applied to the next keyboard event that is read.  The modifier bar is
-displayed when the global minor mode @code{modifier-bar-mode} is
-enabled; to do so, type @kbd{M-x modifier-bar-mode}.
+  Keyboards often lack one or more of the modifier keys (@pxref{Modifier
+Keys}) that Emacs users might want to use, making it difficult or
+impossible to input key sequences with these modifiers.  For example,
+many keyboards lack the Hyper and Super modifiers, and smartphones
+usually also lack Ctrl and Alt modifiers.  Emacs can optionally display
+a tool bar of buttons that can substitute the modifier keys; this
+additional tool bar is known as the @dfn{modifier bar}.  Clicking a
+button within the modifier bar will cause the modifier key shown on the
+button to be applied to the next keyboard event that Emacs reads.  The
+modifier bar is displayed when the global minor mode
+@code{modifier-bar-mode} is enabled; to do so, type @kbd{M-x
+modifier-bar-mode}.
 
 @node Tab Bars
 @section Tab Bars

diff --git a/lisp/tool-bar.el b/lisp/tool-bar.el
index 384b926349d46e7cc5a1edba07ad4d758b58029f..bc4f8acf6d0a46d34d0ade5a6871bb1cd2a018b3 100644 (file)
--- a/lisp/tool-bar.el
+++ b/lisp/tool-bar.el
@@ -532,12 +532,13 @@ decoding the current key sequence, nil otherwise."
   (not (memq modifier modifier-bar-modifier-list)))
 
 (define-minor-mode modifier-bar-mode
-  "Toggle display of the modifier bar.
+  "Toggle display of the key-modifier tool bar.
 
-When enabled, a small tool bar will be displayed next to the tool
-bar containing items bound to
-`tool-bar-event-apply-control-modifier' and its related commands,
-which see."
+When enabled, a small tool bar will be displayed in addition to the
+regular tool bar, containing buttons for key modifiers such as
+Ctrl, Shift, Alt, etc.  This is useful on terminals whose keyboard
+has no keys for these modifiers, such as smartphones and other
+devices with small keyboards."
   :init-value nil
   :global t
   :group 'tool-bar